feat: pair trezor passphrase hidden wallets by jvsena42 · Pull Request #1142 · synonymdev/bitkit-android

jvsena42 · 2026-08-06T18:01:36Z

This PR:

Adds an optional Passphrase path to the Connect Hardware flow, so the hidden wallets of a paired Trezor can be watched alongside its standard wallet
Tracks each passphrase-derived account set as its own hardware wallet identity, with its own home tile, funds label, activity scope and removal
Asks for the passphrase again before signing a transfer when the Trezor session that held it is gone, and refuses to sign if it opens a different wallet
Lets the connect flow offer an already paired device, so passphrase wallets can be added after the initial pairing
Fixes a Trezor Bridge session bug that blocked every passphrase pairing after the first on the emulator

Description

Trezor keeps no record of its hidden wallets and forgets a passphrase with the session, so Bitkit watches each one by its extended public keys and asks for the passphrase again whenever a session has to be rebuilt. The passphrase is never persisted or logged, and both entry screens block screenshots and screen recording the same way the wallet's own passphrase screens do.

A device previously mapped to a single wallet. It now maps to one identity per passphrase, keyed by the wallet id derived from its accounts rather than by the transport id, which two identities on the same device share. Watchers, balances, activity, labels and removal all follow that identity, and removing one hidden wallet leaves the others paired.

Pairing a hidden wallet adds an entry next to the standard one instead of replacing it. The device is matched by shared key material, so re-reading accounts updates the right entry while a different passphrase creates a new one. Only the identity that currently holds the device session shows as connected, since only that one can sign.

Before signing a transfer, Bitkit reopens the hidden wallet and accepts the session only if its accounts resolve back to the wallet being spent from. A wrong passphrase is not rejected by the device — it silently derives another wallet — so the mismatch is caught, the stray wallet that reading its accounts created is dropped, and the transfer fails instead of signing from the wrong wallet. A session that is still open signs with no prompt.

Discovery skips devices that are already paired, which left the Add Hardware Wallet button searching forever and made the passphrase step unreachable after the first pairing. It now falls back to offering a known reachable device once no new one is found.

Separately, the Bridge transport used for the emulator offered a released session id as the previous one when re-acquiring, and the bridge answered wrong previous session. Since switching to a passphrase wallet closes and reopens the session, this blocked every passphrase pairing after the first. This only affects builds with the Bridge enabled; USB and BLE are unaffected.

Preview

no-wallet-add-with-passphrase.webm

Add.multiple.passphrase.wallets.webm

add-repeated-passphrase-wallet.webm

passphrase-disabled.webm

remove-wallet.webm

rename-wallet.webm

transfer-current-session.webm

transfer-other-section.mp4

QA Notes

Needs a Trezor with passphrase protection enabled. On the emulator start it with TREZOR_PASSPHRASE_PROTECTION=true ../bitkit-docker/scripts/trezor-emulator start and confirm on the device for every account a passphrase session reads, otherwise the call blocks until it times out.

Manual Tests

Automated Checks

Unit tests added: cover a passphrase wallet being added next to the standard one, the flag surviving reconnects, and credentials surviving a scoped removal in TrezorRepoTest.kt.
Unit tests added: cover two identities on one device, per-identity balances, connected state, funding account, scoped removal, and connectWithPassphrase including the already-watched case and a device with passphrase protection off in HwWalletRepoTest.kt.
Unit tests added: cover the passphrase step effects, the duplicate toast, the label prefill, the paired step following the right identity, and the fallback to an already paired device in HwConnectViewModelTest.kt.
Unit tests added: cover signing with a live session, prompting once it is gone, and refusing a passphrase that opens another wallet in TransferViewModelTest.kt.
Unit tests added: cover re-acquiring after a release without the stale session in TrezorBridgeTransportTest.kt.
Unit tests modified: existing hardware tests moved to wallet-id keying in HwWalletRepoTest.kt, TransferViewModelTest.kt and HwConnectViewModelTest.kt.
Journeys added: passphrase-pairing.xml, passphrase-duplicate.xml, passphrase-settings-remove.xml and passphrase-transfer-to-spending.xml, including checks that the passphrase never reaches the logs or datastore.
Verified on a Pixel emulator against the Trezor emulator: pairing two hidden wallets alongside the standard one, per-identity labels, three home tiles, the connected indicator, and no passphrase in the logs. The duplicate, settings-remove and transfer journeys were not executed; the transfer one additionally needs regtest funds on a hidden wallet.
CI: standard compile, unit test and detekt checks run by the PR bot.

Known gaps

A hidden wallet can persist with only part of its accounts when a read fails with a device error that is not classified as transient, and its wallet id would change once the missing accounts are read. This is a pre-existing gap in the partial-save guard that passphrase sessions make easier to hit.
Two hidden wallets on the same device default to the same name until renamed, since the default label is the device name.

… scope of this branch

… its transport

…ction, doesn't exist when it's called and the mismatch path tears down the session before a retry

…rries

…eId in it.deviceIds } and unconditionally writes pairedWalletId = wallet.id, so a wallets emission that does not yet contain the just-added hidden wallet resets the paired identity back to the standard wallet.

…se POST, so a failed release still leaves the stale session id cached.

greptile-apps · 2026-08-10T10:08:35Z

Greptile Summary

The PR adds independently tracked Trezor hidden-wallet identities and passphrase-based session restoration while preserving wallet-scoped balances, activity, labels, signing, and removal.

Keys hardware-wallet state and watchers by derived wallet identity instead of transport ID.
Adds passphrase pairing and signing-reconnection flows with wallet-identity verification.
Keeps sibling identities and transport credentials when removing one hidden wallet.
Refreshes stale Trezor Bridge sessions before retrying acquisition.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
app/src/main/java/to/bitkit/repositories/HwWalletRepo.kt	Moves hardware-wallet aggregation, watcher lifecycle, signing, and removal to wallet-identity scope; the previously reported multi-transport removal issue is addressed.
app/src/main/java/to/bitkit/repositories/TrezorRepo.kt	Persists multiple identities per physical device and manages passphrase-bound sessions while atomically filtering scoped removals.
app/src/main/java/to/bitkit/services/TrezorBridgeTransport.kt	Clears released sessions and retries acquisition after refreshing a stale Bridge session.
app/src/main/java/to/bitkit/viewmodels/TransferViewModel.kt	Integrates passphrase restoration and identity verification into hardware-wallet signing.
app/src/main/java/to/bitkit/ui/sheets/hardware/HwConnectViewModel.kt	Adds passphrase-wallet pairing, duplicate handling, and known-device discovery fallback.
app/src/main/java/to/bitkit/ui/screens/transfer/hardware/HwPassphrasePromptSheet.kt	Adds the intentionally unmasked, screenshot-protected passphrase prompt used to restore signing sessions.

Sequence Diagram

sequenceDiagram
    participant UI as Hardware Wallet UI
    participant HW as HwWalletRepo
    participant TR as TrezorRepo
    participant Device as Trezor
    participant Store as HwWalletStore
    UI->>HW: connectWithPassphrase(deviceId, passphrase)
    HW->>TR: set/connect passphrase wallet mode
    TR->>Device: Open fresh passphrase session
    Device-->>TR: Features and account keys
    TR->>Store: Persist identity by derived wallet ID
    TR-->>HW: Connected wallet identity
    HW-->>UI: Add or select hidden-wallet tile
    UI->>HW: Sign from wallet ID
    alt matching session is live
        HW->>Device: Sign transaction
    else session is absent or belongs to another identity
        UI->>HW: reconnectWithPassphrase(walletId, passphrase)
        HW->>TR: Open fresh passphrase session
        TR->>Device: Read account keys
        alt derived wallet ID matches
            HW->>Device: Sign transaction
        else derived wallet ID differs
            HW->>TR: Disconnect stray session
            HW-->>UI: Reject passphrase mismatch
        end
    end

_{Reviews (3): Last reviewed commit: "fix: passphrase should not gate pending ..." | Re-trigger Greptile}

… Trezor suite

jvsena42 · 2026-08-10T16:21:07Z

checking CI failures

Edit: both are backend failures

…ed ones

jvsena42 · 2026-08-13T11:01:34Z

All test passing. Re-runned manual tests checklist with journeys

ovitrif

Looks good, passphrase identities stay scoped to their own tiles, session, and removal without replacing the standard wallet.

jvsena42 added 13 commits August 6, 2026 11:28

feat: identity data model + walletId keying

b537530

test: cover hw multi-wallet identities

57b1c75

feat: add Trezor passphrase wallet pairing

4d9faff

feat: verify passphrase before hw signing

dd794a0

feat: add screenshot protection for passphrase inputs

9cbb34e

feat: add shield image

0a9e5b9

test: add passphrase wallet journeys

d676acc

fix: shield shrink

cb0550a

fix: coin stack image padding

d833939

fix: prefill passphrase wallet name

f993806

test: update journeys passphrase flow

c203bc5

fix: TrezorBridgeTransport reused a released session id on re-acquire

8885a6f

chore: rename changelog fragment

ade56eb

jvsena42 self-assigned this Aug 6, 2026

jvsena42 added 12 commits August 7, 2026 08:03

Merge branch 'master' into feat/hw-passphrase-wallets

f6f0dae

refactor: replace runCatching with runSuspendCatching, limited to the…

b95a582

… scope of this branch

fix: HW wallet label persistence

7117b38

fix: resolve HW wallet name from wallet id

7e4c8e3

fix: use stored devices as source of true when deleting

37b22b2

fix: make the device section belongs to walletId instead of merely to…

6c2e2d9

… its transport

fix: reconnectWithPassphrase requires a live session that, by constru…

712914d

…ction, doesn't exist when it's called and the mismatch path tears down the session before a retry

fix: report failure if no target is found

e21c660

fix: cancel hwTransferSignJob when dismiss passphrase

bfd61d7

fix: check connectedWalletId on forgetDevice instead of only deviceId

891d9bf

fix: connect now supersedes entries of a seed the device no longer ca…

6aac9f3

…rries

fix: add guard to passphraseProtected to protect default wallets

35824b4

github-advanced-security AI found potential problems Aug 7, 2026

View reviewed changes

Comment thread app/src/test/java/to/bitkit/repositories/TrezorRepoTest.kt Fixed

jvsena42 added 3 commits August 7, 2026 14:11

fix: warns if walletId was not found in onFinishClick

97165e7

fix: observeConnectedWallet falls back to wallets.firstOrNull { devic…

e14d114

…eId in it.deviceIds } and unconditionally writes pairedWalletId = wallet.id, so a wallets emission that does not yet contain the just-added hidden wallet resets the paired identity back to the standard wallet.

fix: Released-session cleanup sits inside runCatching after the relea…

a9a6a9d

…se POST, so a failed release still leaves the stale session id cached.

chore: lint

b64c6d4

jvsena42 marked this pull request as ready for review August 10, 2026 10:05

greptile-apps Bot reviewed Aug 10, 2026

View reviewed changes

Comment thread app/src/main/java/to/bitkit/ui/screens/transfer/hardware/HwPassphrasePromptSheet.kt

Comment thread app/src/main/java/to/bitkit/repositories/TrezorRepo.kt

jvsena42 marked this pull request as draft August 10, 2026 10:11

jvsena42 added 3 commits August 10, 2026 07:17

fix: dont override label when transport id changes

fdc48d7

fix: ensure forgetDevice remove an identity from all transport layers

0932740

fix: display specific error when passphrase protection is disabled on…

91ed521

… Trezor suite

jvsena42 marked this pull request as ready for review August 10, 2026 11:33

jvsena42 requested a review from ovitrif August 10, 2026 11:55

jvsena42 requested review from ovitrif and removed request for ovitrif August 10, 2026 16:21

jvsena42 added this to the 2.5.0 milestone Aug 11, 2026

jvsena42 mentioned this pull request Aug 11, 2026

feat: pair trezor passphrase hidden wallets synonymdev/bitkit-ios#662

Open

17 tasks

This comment was marked as resolved.

Sign in to view

fix: improve unresolved session handling

3a5e39f

This comment was marked as resolved.

Sign in to view

jvsena42 marked this pull request as draft August 12, 2026 17:17

This comment was marked as resolved.

Sign in to view

jvsena42 removed the request for review from ovitrif August 12, 2026 17:17

jvsena42 added 3 commits August 13, 2026 06:52

fix: do not adopt an identity while the device holds several unresolv…

297f921

…ed ones

fix: differentiate lost section from passphrase protection disabled

815aa1a

fix: passphrase should not gate pending broadcast

04b3f4d

jvsena42 marked this pull request as ready for review August 13, 2026 09:54

jvsena42 requested a review from ovitrif August 13, 2026 11:01

ovitrif approved these changes Aug 14, 2026

View reviewed changes

jvsena42 merged commit 92c085a into master Aug 14, 2026
27 checks passed

jvsena42 deleted the feat/hw-passphrase-wallets branch August 14, 2026 10:12

Navigation Menu

Uh oh!

feat: pair trezor passphrase hidden wallets - #1142

feat: pair trezor passphrase hidden wallets#1142
jvsena42 merged 36 commits into
masterfrom
feat/hw-passphrase-wallets

jvsena42 commented Aug 6, 2026 •

edited

Loading

Uh oh!

Uh oh!

greptile-apps Bot commented Aug 10, 2026 •

edited

Loading

Important Files Changed

Uh oh!

Uh oh!

Uh oh!

jvsena42 commented Aug 10, 2026 •

edited

Loading

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

jvsena42 commented Aug 13, 2026

Uh oh!

ovitrif left a comment •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

jvsena42 commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Preview

QA Notes

Manual Tests

Automated Checks

Known gaps

Uh oh!

Uh oh!

greptile-apps Bot commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Sequence Diagram

Uh oh!

Uh oh!

Uh oh!

jvsena42 commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

jvsena42 commented Aug 13, 2026

Uh oh!

ovitrif left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jvsena42 commented Aug 6, 2026 •

edited

Loading

greptile-apps Bot commented Aug 10, 2026 •

edited

Loading

jvsena42 commented Aug 10, 2026 •

edited

Loading

ovitrif left a comment •

edited

Loading